/*
 * Copyright (c) 2025 Huawei Device Co., Ltd.
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/**
 * @addtogroup OHAudioSuite
 * @{
 *
 * @brief 提供音频编创相关C接口定义。
 *
 * @since 22
 * @version 1.0
 */
/**
 * @file native_audio_suite_engine.h
 *
 * @brief 声明与音频编创相关的接口。
 * （包括引擎、管线、节点）。
 *
 * @library libohaudiosuite.so
 * @syscap SystemCapability.Multimedia.Audio.SuiteEngine
 * @kit AudioKit
 * @include <ohaudiosuite/native_audio_suite_engine.h>
 * @since 22
 * @version 1.0
 */
#ifndef NATIVE_AUDIO_SUITE_ENGINE_H
#define NATIVE_AUDIO_SUITE_ENGINE_H
#include "native_audio_suite_base.h"
#ifdef __cplusplus
extern "C" {
#endif
/**
 * @brief 创建音频编创引擎。
 *
 * @param audioSuiteEngine 音频编创引擎句柄，指向接收audioSuiteEngine变量的指针。
 * @return AUDIOSUITE_SUCCESS：函数执行成功。\n
 *         AUDIOSUITE_ERROR_INVALID_PARAM：参数audioSuiteEngine为空指针。\n
 *         AUDIOSUITE_ERROR_INVALID_STATE：引擎已经被初始化。\n
 *         AUDIOSUITE_ERROR_MEMORY_ALLOC_FAILED：内存申请失败。\n
 *         AUDIOSUITE_ERROR_SYSTEM：系统发生其他异常。
 * @since 22
 */
OH_AudioSuite_Result OH_AudioSuiteEngine_Create(OH_AudioSuiteEngine** audioSuiteEngine);

/**
 * @brief 销毁音频编创引擎句柄。
 *
 * @note 销毁引擎时会同时销毁该引擎下的所有管线。
 *
 * @param audioSuiteEngine 音频编创引擎句柄，通过{@link OH_AudioSuiteEngine_Create}获取句柄。
 * @return AUDIOSUITE_SUCCESS：函数执行成功。\n
 *         AUDIOSUITE_ERROR_INVALID_PARAM：参数audioSuiteEngine为空指针。\n
 *         AUDIOSUITE_ERROR_INVALID_STATE：引擎已被去初始化、引擎未创建或未初始化引擎。\n
 *         AUDIOSUITE_ERROR_SYSTEM：系统发生其他异常。
 * @since 22
 */
OH_AudioSuite_Result OH_AudioSuiteEngine_Destroy(OH_AudioSuiteEngine* audioSuiteEngine);

/**
 * @brief 在当前音频编创引擎中创建1个管线。
 *
 * 管线是引擎内负责音频编创的执行单元，1个引擎可创建多个管线。\n
 * 支持最多创建10条管线，其中至多有1条实时渲染管线。\n
 * 每个管线必须至少包含1个输入节点，有且只有1个输出节点。\n
 * 当管线在{@link OH_AudioSuite_PipelineWorkMode}.AUDIOSUITE_PIPELINE_EDIT_MODE模式下工作时，支持所有的效果节点。\n
 * 当管线在{@link OH_AudioSuite_PipelineWorkMode}.AUDIOSUITE_PIPELINE_REALTIME_MODE模式下工作时，
 * 仅支持{@link OH_AudioNode_Type}.EFFECT_NODE_TYPE_EQUALIZER效果节点。
 *
 * @param audioSuiteEngine 音频编创引擎句柄。通过{@link OH_AudioSuiteEngine_Create}获取句柄。
 * @param audioSuitePipeline 音频编创管线句柄。
 * @param workMode 管线工作模式。\n
 * 1. AUDIOSUITE_PIPELINE_EDIT_MODE: 支持所有效果节点；\n
 * 2. AUDIOSUITE_PIPELINE_REALTIME_MODE：支持均衡器等节点。
 * @return AUDIOSUITE_SUCCESS：函数执行成功。\n
 *         AUDIOSUITE_ERROR_INVALID_PARAM：参数audioSuiteEngine为空指针或参数audioSuitePipeline为空指针。\n
 *         AUDIOSUITE_ERROR_ENGINE_NOT_EXIST：未初始化引擎。\n
 *         AUDIOSUITE_ERROR_CREATED_EXCEED_SYSTEM_LIMITS：创建管线数量超过系统最大数量限制（引擎最多创建10条管线）。\n
 *         AUDIOSUITE_ERROR_TIMEOUT：操作处理超时。\n
 *         AUDIOSUITE_ERROR_MEMORY_ALLOC_FAILED：内存申请失败。\n
 *         AUDIOSUITE_ERROR_SYSTEM：系统发生其他异常。
 * @since 22
 */
OH_AudioSuite_Result OH_AudioSuiteEngine_CreatePipeline(
    OH_AudioSuiteEngine* audioSuiteEngine,
    OH_AudioSuitePipeline** audioSuitePipeline, OH_AudioSuite_PipelineWorkMode workMode);

/**
 * @brief 销毁音频编创管线句柄。
 *
 * @note 销毁管线时会同时销毁该管线下的所有节点。
 *
 * @param audioSuitePipeline 音频编创管线句柄。通过{@link OH_AudioSuiteEngine_CreatePipeline}获取需要销毁的句柄。
 * @return AUDIOSUITE_SUCCESS：函数执行成功。\n
 *         AUDIOSUITE_ERROR_INVALID_PARAM：参数audioSuitePipeline为空指针。\n
 *         AUDIOSUITE_ERROR_PIPELINE_NOT_EXIST：管线不存在或已经被销毁。\n
 *         AUDIOSUITE_ERROR_TIMEOUT：操作处理超时。\n
 *         AUDIOSUITE_ERROR_SYSTEM：系统发生其他异常。
 * @since 22
 */
OH_AudioSuite_Result OH_AudioSuiteEngine_DestroyPipeline(OH_AudioSuitePipeline* audioSuitePipeline);

/**
 * @brief 开始运行该管线，管线会进入{@link OH_AudioSuite_PipelineState}.AUDIOSUITE_PIPELINE_RUNNING运行状态。
 *
 * @param audioSuitePipeline 音频编创管线句柄。通过{@link OH_AudioSuiteEngine_CreatePipeline}获取句柄。
 * @return AUDIOSUITE_SUCCESS：函数执行成功。\n
 *         AUDIOSUITE_ERROR_INVALID_PARAM：参数audioSuitePipeline为空指针。\n
 *         AUDIOSUITE_ERROR_PIPELINE_NOT_EXIST：管线不存在或已经被销毁。\n
 *         AUDIOSUITE_ERROR_INVALID_STATE：管线已在运行或节点连接异常。\n
 *         可能的原因如下：\n
 *         1. 管线已经在运行状态；\n
 *         2. 当前管线中不存在输出类型节点；\n
 *         3. 起始节点不是输入类型节点。\n
 *         AUDIOSUITE_ERROR_TIMEOUT：操作处理超时。\n
 *         AUDIOSUITE_ERROR_SYSTEM：系统发生其他异常。
 * @since 22
 */
OH_AudioSuite_Result OH_AudioSuiteEngine_StartPipeline(OH_AudioSuitePipeline* audioSuitePipeline);

/**
 * @brief 停止运行该管线，管线会进入{@link OH_AudioSuite_PipelineState}.AUDIOSUITE_PIPELINE_STOPPED停止状态。
 *
 * 该函数不会改变管线中节点之间的连接关系，管线一旦被停止，
 * {@link OH_AudioSuiteEngine_RenderFrame}就不能再进行音频处理。
 *
 * @param audioSuitePipeline 音频编创管线句柄。通过{@link OH_AudioSuiteEngine_CreatePipeline}获取句柄。
 * @return AUDIOSUITE_SUCCESS：函数执行成功。\n
 *         AUDIOSUITE_ERROR_INVALID_PARAM：参数audioSuitePipeline为空指针。\n
 *         AUDIOSUITE_ERROR_PIPELINE_NOT_EXIST：管线不存在或已经被销毁。\n
 *         AUDIOSUITE_ERROR_INVALID_STATE：管线已经在停止状态或仍在渲染中。\n
 *         AUDIOSUITE_ERROR_TIMEOUT：操作处理超时。\n
 *         AUDIOSUITE_ERROR_SYSTEM：系统发生其他异常。
 * @since 22
 */
OH_AudioSuite_Result OH_AudioSuiteEngine_StopPipeline(OH_AudioSuitePipeline* audioSuitePipeline);

/**
 * @brief 获取当前管线的状态。
 *
 * @param audioSuitePipeline 音频编创管线句柄。通过{@link OH_AudioSuiteEngine_CreatePipeline}获取句柄。
 * @param pipelineState 管线状态的输出参数。
 * @return AUDIOSUITE_SUCCESS：函数执行成功。\n
 *         AUDIOSUITE_ERROR_INVALID_PARAM：参数无效。例如，audioSuitePipeline为空指针等。\n
 *         AUDIOSUITE_ERROR_PIPELINE_NOT_EXIST：管线不存在或已经被销毁。\n
 *         AUDIOSUITE_ERROR_TIMEOUT：操作处理超时。\n
 *         AUDIOSUITE_ERROR_SYSTEM：系统发生其他异常。
 * @since 22
 */
OH_AudioSuite_Result OH_AudioSuiteEngine_GetPipelineState(
    OH_AudioSuitePipeline* audioSuitePipeline, OH_AudioSuite_PipelineState* pipelineState);

/**
 * @brief 应用调用此接口获取管线处理后的音频数据（针对单输出效果节点）。
 *
 * @note 应用程序需调用此接口获取经过效果处理后的音频数据。
 * 调用后，管线会从输出节点向前依次拉取数据、应用效果处理，
 * 最终将处理后的数据填充到应用程序传入的audioData指针中。\n
 * 系统会尝试按requestFrameSize请求的大小填充数据，实际处理的数据大小通过responseSize返回给应用程序。\n
 * 当应用程序为所有输入节点准备好数据并通过回调提交最后一次数据时，应在回调中设置finish标志位。
 * 当管线中所有输入都传递了finish标志后，处理完成后会通过finishedFlag通知应用程序。
 * 若finishedFlag为true，应用程序不应再调用此接口。
 *
 * @param audioSuitePipeline 音频编创管线句柄。通过{@link OH_AudioSuiteEngine_CreatePipeline}获取句柄。
 * @param audioData 获取音频需要写入的数据地址。
 * @param requestFrameSize audioData的内存字节大小，需大于0。
 * @param responseSize 管线写入audioData的音频数据大小，不会大于requestFrameSize。
 * @param finishedFlag 标识当前管线是否渲染完成。
 * @return AUDIOSUITE_SUCCESS：函数执行成功。\n
 *         AUDIOSUITE_ERROR_INVALID_PARAM：参数为空指针或无效值。\n
 *         可能的原因如下：\n
 *         1. 参数audioSuitePipeline为空指针；\n
 *         2. 参数audioData为空指针；\n
 *         3. 参数requestFrameSize小于等于0；\n
 *         4. 参数responseSize为空指针；\n
 *         5. 参数finishedFlag为空指针。\n
 *         AUDIOSUITE_ERROR_PIPELINE_NOT_EXIST：管线不存在或已经被销毁。\n
 *         AUDIOSUITE_ERROR_INVALID_STATE：管线不在运行状态。\n
 *         AUDIOSUITE_ERROR_UNSUPPORTED_OPERATION：管线渲染已完成（之前调用该接口时finishedFlag已写入为true）。\n
 *         AUDIOSUITE_ERROR_TIMEOUT：操作处理超时。\n
 *         AUDIOSUITE_ERROR_SYSTEM：系统发生其他异常。
 * @since 22
 */
OH_AudioSuite_Result OH_AudioSuiteEngine_RenderFrame(OH_AudioSuitePipeline* audioSuitePipeline,
    void* audioData, int32_t requestFrameSize, int32_t* responseSize, bool* finishedFlag);

/**
 * @brief 渲染该管线，获取管线处理后的音频数据。
 *
 * 针对多输出效果节点，比如包含音源分离节点的管线，audioDataArray的大小需与效果节点的输出数量一一对应
 * （例如：音源分离节点需两个：第1个为人声，第2个为背景声）。
 *
 * @param audioSuitePipeline 音频编创管线句柄。通过{@link OH_AudioSuiteEngine_CreatePipeline}获取句柄。
 * @param audioDataArray 用户读取音频数据时所使用的数组指针，每个一维数组大小需一致。
 * @param responseSize 管线写入audioData的音频数据大小。系统会确保每个一维数组被填充的数据大小一致。
 * @param finishedFlag 标记当前管线是否渲染完成。
 * @return AUDIOSUITE_SUCCESS：函数执行成功。\n
 *         AUDIOSUITE_ERROR_INVALID_PARAM：参数为空指针或无效值。\n
 *         可能的原因如下：\n
 *         1. 参数audioSuitePipeline为空指针；\n
 *         2. 参数audioDataArray为空指针；\n
 *         3. 参数audioDataArray中的某个成员为空指针；\n
 *         4. 参数audioDataArray中的requestFrameSize小于等于0；\n
 *         5. 参数responseSize为空指针；\n
 *         6. 参数finishedFlag为空指针。\n
 *         AUDIOSUITE_ERROR_PIPELINE_NOT_EXIST：管线不存在或已经被销毁。\n
 *         AUDIOSUITE_ERROR_INVALID_STATE：管线不在运行状态。\n
 *         AUDIOSUITE_ERROR_UNSUPPORTED_OPERATION：管线渲染已完成（之前调用该接口时finishedFlag已写入为true）。\n
 *         AUDIOSUITE_ERROR_TIMEOUT：操作处理超时。\n
 *         AUDIOSUITE_ERROR_SYSTEM：系统发生其他异常。
 * @since 22
 */
OH_AudioSuite_Result OH_AudioSuiteEngine_MultiRenderFrame(OH_AudioSuitePipeline* audioSuitePipeline,
    OH_AudioDataArray* audioDataArray, int32_t* responseSize, bool* finishedFlag);

/**
 * @brief 获取一个音频编创节点构造器，用于配置并创建音频节点。
 *
 * 构建器可复用，但若新节点属性与之前不同，必须使用{@link OH_AudioSuiteNodeBuilder_Reset()}重置。
 *
 * @param builder 音频编创节点构造器句柄。
 * @return AUDIOSUITE_SUCCESS：函数执行成功。\n
 *         AUDIOSUITE_ERROR_INVALID_PARAM：参数无效。例如，builder为空指针。\n
 *         AUDIOSUITE_ERROR_MEMORY_ALLOC_FAILED：内存申请失败。\n
 *         AUDIOSUITE_ERROR_SYSTEM：系统发生其他异常。
 * @since 22
 */
OH_AudioSuite_Result OH_AudioSuiteNodeBuilder_Create(OH_AudioNodeBuilder** builder);

/**
 * @brief 销毁一个音频编创节点构造器。
 *
 * 使用完构造器后必须调用此函数进行销毁。
 *
 * @param builder 音频编创节点构造器句柄。通过{@link OH_AudioSuiteNodeBuilder_Create}获取句柄。
 * @return AUDIOSUITE_SUCCESS：函数执行成功。\n
 *         AUDIOSUITE_ERROR_INVALID_PARAM：参数无效。例如，builder为空指针。\n
 *         AUDIOSUITE_ERROR_SYSTEM：系统发生其他异常。
 * @since 22
 */
OH_AudioSuite_Result OH_AudioSuiteNodeBuilder_Destroy(OH_AudioNodeBuilder* builder);

/**
 * @brief 重置一个音频编创节点构造器，同时将之前使用接口设置参数重置。
 *
 * 若需复用构建器创建属性不同的新节点，必须调用此接口清除所有属性（如节点类型等）。
 *
 * @param builder 音频编创节点构造器句柄。通过{@link OH_AudioSuiteNodeBuilder_Create}获取句柄。
 * @return AUDIOSUITE_SUCCESS：函数执行成功。\n
 *         AUDIOSUITE_ERROR_INVALID_PARAM：参数无效。例如，builder为空指针。\n
 *         AUDIOSUITE_ERROR_SYSTEM：系统发生其他异常。
 * @since 22
 */
OH_AudioSuite_Result OH_AudioSuiteNodeBuilder_Reset(OH_AudioNodeBuilder* builder);

/**
 * @brief 设置当前节点构造器需要构造的节点类型。
 *
 * 创建节点时会根据类型验证其他参数，所有节点类型的创建均需设置此属性。
 *
 * @param builder 音频编创节点构造器句柄。通过{@link OH_AudioSuiteNodeBuilder_Create}获取句柄。
 * @param type 节点类型。
 * @return AUDIOSUITE_SUCCESS：配置节点类型成功。\n
 *         AUDIOSUITE_ERROR_INVALID_PARAM：参数无效，例如，builder为空指针。\n
 *         AUDIOSUITE_ERROR_SYSTEM：系统发生其他异常。
 * @since 22
 */
OH_AudioSuite_Result OH_AudioSuiteNodeBuilder_SetNodeType(OH_AudioNodeBuilder* builder, OH_AudioNode_Type type);

/**
 * @brief 配置输入/输出节点的音频格式。
 * 其余节点不配置，且只能在创建节点之前使用。
 *
 * 对于输入节点，此函数可使应用指定写入数据的音频格式；\n
 * 对于输出节点，此函数可使应用指定其期望获取数据的音频格式；\n
 * 对于其他类型的节点则不支持调用此函数进行音频格式设置。
 *
 * @param builder 音频编创节点构造器句柄。通过{@link OH_AudioSuiteNodeBuilder_Create}获取句柄。
 * @param audioFormat 音频流格式。
 * @return AUDIOSUITE_SUCCESS：函数执行成功。\n
 *         AUDIOSUITE_ERROR_INVALID_PARAM：参数无效，例如，builder为空指针。\n
 *         AUDIOSUITE_ERROR_UNSUPPORTED_FORMAT：audioFormat中的channelCount不支持。\n
 *         AUDIOSUITE_ERROR_SYSTEM：系统发生其他异常。
 * @since 22
 */
OH_AudioSuite_Result OH_AudioSuiteNodeBuilder_SetFormat(OH_AudioNodeBuilder* builder, OH_AudioFormat audioFormat);

/**
 * @brief 配置输入节点的请求数据回调函数。
 *
 * @note 用户把需要处理的PCM音频数据写入到audioData，OHAudioSuite从audioData拿到数据进行音频编创。\n
 * 应用程序在此回调中向audioData写入不超过audioDataSize大小的数据。\n
 * 当所有数据通过回调传递给管线后，应用程序应在最后一次回调中将finished设为true，此后管线不再调用此接口。\n
 * 只有输入节点需要配置，其余节点不配置。
 *
 * @param audioNode 音频编创节点句柄。通过{@link OH_AudioSuiteEngine_CreateNode}获取句柄。
 * @param userData 用户使用的数据指针。系统调用此回调函数时，
 * 将使用{@link OH_AudioSuiteNodeBuilder_SetRequestDataCallback}接口传入的userData。
 * @param audioData 系统提供的内存地址，用于将需要处理的音频数据流写入（需由用户填充）。
 * @param audioDataSize audioData内存地址的字节大小。
 * @param finished 标记audioNode节点需要处理的音频数据流是否已经写入完成。
 * true表示已完成，false表示未完成。
 * @return 写入audioData缓冲区的有效数据长度（单位为字节）。\n
 * 返回值范围必须在[0, audioDataSize]范围内，如果返回值小于0，系统会将其修改为0，
 * 如果返回值大于audioDataSize，系统会将其修改为audioDataSize。
 * @since 22
 */
typedef int32_t (*OH_InputNode_RequestDataCallback)(
    OH_AudioNode* audioNode, void* userData, void* audioData, int32_t audioDataSize, bool* finished);

/**
 * @brief 配置当前输入节点构造器的写入音频数据回调函数。
 *
 * @param builder 音频编创节点构造器句柄。通过{@link OH_AudioSuiteNodeBuilder_Create}获取句柄。
 * @param callback 写入当前节点音频数据的回调接口。
 * @param userData 用户自定义数据，会在callback函数中将地址传入给用户，如果不使用，可以传入空指针。
 * @return AUDIOSUITE_SUCCESS：函数执行成功。\n
 *         AUDIOSUITE_ERROR_INVALID_PARAM：\n
 *         可能的原因如下：\n
 *         1. 参数builder为空指针；\n
 *         2. 参数callback为空指针。\n
 *         AUDIOSUITE_ERROR_TIMEOUT：操作处理超时。\n
 *         AUDIOSUITE_ERROR_SYSTEM：系统发生其他异常。
 * @since 22
 */
OH_AudioSuite_Result OH_AudioSuiteNodeBuilder_SetRequestDataCallback(
    OH_AudioNodeBuilder* builder, OH_InputNode_RequestDataCallback callback, void* userData);

/**
 * @brief 根据音频编创构造器在音频管线中构造一个音频节点。
 *
 * 当执行此函数，系统会基于builder中设置的节点类型校验参数的合法性。\n
 * 应用可以通过返回值确定错误发生的原因。
 *
 * @param audioSuitePipeline 音频编创管线句柄。通过{@link OH_AudioSuiteEngine_CreatePipeline}获取句柄。
 * @param builder 音频编创节点构造器句柄。通过{@link OH_AudioSuiteNodeBuilder_Create}获取句柄。
 * @param audioNode 音频编创节点句柄。
 * @return AUDIOSUITE_SUCCESS：函数执行成功。\n
 *         AUDIOSUITE_ERROR_INVALID_PARAM：参数为空指针或无效值。\n
 *         可能的原因如下：\n
 *         1. 参数audioSuitePipeline为空指针；\n
 *         2. 参数builder为空指针；\n
 *         3. 参数audioNode为空指针。\n
 *         AUDIOSUITE_ERROR_CREATED_EXCEED_SYSTEM_LIMITS：当构建当前类型的节点数量超过管线限制。
 *         例如，创建效果类节点超过5个。\n
 *         AUDIOSUITE_ERROR_REQUIRED_PARAMETERS_MISSING：构建builder中type类型的节点时缺少必要参数。
 *         例如，builder未设置节点类型。\n
 *         AUDIOSUITE_ERROR_UNSUPPORTED_OPERATION：当前构造器节点类型为输出节点但设置了回调函数，
 *         或构造器节点类型为效果节点但设置了音频格式或回调函数。\n
 *         AUDIOSUITE_ERROR_TIMEOUT：操作处理超时。\n
 *         AUDIOSUITE_ERROR_MEMORY_ALLOC_FAILED：内存申请失败。\n
 *         AUDIOSUITE_ERROR_SYSTEM：系统发生其他异常。
 *
 * @since 22
 */
OH_AudioSuite_Result OH_AudioSuiteEngine_CreateNode(
    OH_AudioSuitePipeline* audioSuitePipeline, OH_AudioNodeBuilder* builder, OH_AudioNode** audioNode);

/**
 * @brief 销毁一个音频编创节点。
 *
 * 管线必须处于{@link OH_AudioSuite_PipelineState}.AUDIOSUITE_PIPELINE_STOPPED停止状态才能删除节点。
 *
 * @param audioNode 音频编创节点句柄。通过{@link OH_AudioSuiteEngine_CreateNode}获取句柄。
 * @return AUDIOSUITE_SUCCESS：函数执行成功。\n
 *         AUDIOSUITE_ERROR_INVALID_PARAM：参数audioNode为空指针。\n
 *         AUDIOSUITE_ERROR_NODE_NOT_EXIST：节点不存在或者当前节点已经被销毁。\n
 *         AUDIOSUITE_ERROR_INVALID_STATE：管线不在停止状态。\n
 *         AUDIOSUITE_ERROR_TIMEOUT：操作处理超时。\n
 *         AUDIOSUITE_ERROR_SYSTEM：系统发生其他异常。
 * @since 22
 */
OH_AudioSuite_Result OH_AudioSuiteEngine_DestroyNode(OH_AudioNode* audioNode);

/**
 * @brief 获取当前节点的效果使能状态。
 *
 * 仅效果节点支持获取。\n
 * 若对输入或输出节点调用此接口，将返回AUDIOSUITE_ERROR_INVALID_PARAM错误码。
 *
 * @param audioNode 音频编创节点句柄。通过{@link OH_AudioSuiteEngine_CreateNode}获取句柄。
 * @param bypassStatus 获取当前效果类节点使能状态，false表示未跳过节点处理，true表示已跳过节点处理。
 * @return AUDIOSUITE_SUCCESS：函数执行成功。\n
 *         AUDIOSUITE_ERROR_INVALID_PARAM：\n
 *         参数audioNode或bypassStatus为空指针。\n
 *         AUDIOSUITE_ERROR_NODE_NOT_EXIST：节点不存在或者当前节点已经被销毁。\n
 *         AUDIOSUITE_ERROR_UNSUPPORTED_OPERATION：audioNode节点类型为非效果类节点。\n
 *         AUDIOSUITE_ERROR_TIMEOUT：操作处理超时。\n
 *         AUDIOSUITE_ERROR_SYSTEM：系统发生其他异常。
 * @since 22
 */
OH_AudioSuite_Result OH_AudioSuiteEngine_GetNodeBypassStatus(
    OH_AudioNode* audioNode, bool* bypassStatus);

/**
 * @brief 设置当前节点的效果使能状态（仅效果节点支持）。
 *
 * 当bypass为true时，效果节点仅透传数据，不进行任何效果处理。\n
 * 当bypass为true时，效果节点进行对应的效果处理。
 *
 * @param audioNode 音频编创节点句柄。通过{@link OH_AudioSuiteEngine_CreateNode}获取句柄。
 * @param bypass 当前效果类节点使能状态。
 * @return AUDIOSUITE_SUCCESS：函数执行成功。\n
 *         AUDIOSUITE_ERROR_INVALID_PARAM：参数audioNode为空指针。\n
 *         AUDIOSUITE_ERROR_NODE_NOT_EXIST：节点不存在或者当前节点已经被销毁。\n
 *         AUDIOSUITE_ERROR_UNSUPPORTED_OPERATION：audioNode为非效果节点。\n
 *         AUDIOSUITE_ERROR_TIMEOUT：操作处理超时。\n
 *         AUDIOSUITE_ERROR_SYSTEM：系统发生其他异常。
 * @since 22
 */
OH_AudioSuite_Result OH_AudioSuiteEngine_BypassEffectNode(OH_AudioNode* audioNode, bool bypass);

/**
 * @brief 配置输入/输出节点的音频格式，在创建节点之后使用，只有输入和输出节点能够设置。
 * 输入节点指定音源格式，输出节点指定目标格式。
 *
 * @param audioNode 音频编创节点句柄。通过{@link OH_AudioSuiteEngine_CreateNode}获取句柄。
 * @param audioFormat 音频流格式。
 * @return AUDIOSUITE_SUCCESS：函数执行成功。\n
 *         AUDIOSUITE_ERROR_INVALID_PARAM：参数audioNode或audioFormat为空指针。\n
 *         AUDIOSUITE_ERROR_NODE_NOT_EXIST：节点不存在或者当前节点已经被销毁。\n
 *         AUDIOSUITE_ERROR_UNSUPPORTED_OPERATION：audioNode是效果节点。\n
 *         AUDIOSUITE_ERROR_INVALID_STATE：管线不在停止状态。\n
 *         AUDIOSUITE_ERROR_TIMEOUT：操作处理超时。\n
 *         AUDIOSUITE_ERROR_SYSTEM：系统发生其他异常。
 * @since 22
 */
OH_AudioSuite_Result OH_AudioSuiteEngine_SetAudioFormat(OH_AudioNode* audioNode, OH_AudioFormat *audioFormat);

/**
 * @brief 连接两个节点，数据流走向从sourceAudioNode到destAudioNode。
 *
 * 连接节点将改变管道拓扑，可能导致部分数据丢失，建议在引擎停止状态下执行此操作。\n
 * 节点连接顺序：输入节点 -> 效果节点 -> 输出节点。
 *
 * @param sourceAudioNode 音频编创节点句柄。通过{@link OH_AudioSuiteEngine_CreateNode}获取句柄。
 * @param destAudioNode 音频编创节点句柄。通过{@link OH_AudioSuiteEngine_CreateNode}获取句柄。
 * @return AUDIOSUITE_SUCCESS：函数执行成功。
 *         AUDIOSUITE_ERROR_INVALID_PARAM：参数sourceAudioNode或destAudioNode为空指针。\n
 *         AUDIOSUITE_ERROR_NODE_NOT_EXIST：节点不存在或者当前节点已经被销毁。\n
 *         AUDIOSUITE_ERROR_UNSUPPORTED_CONNECT：节点之间不支持连接。\n
 *         可能的原因如下：\n
 *         1. 参数sourceAudioNode类型为输出类型节点；\n
 *         2. 参数destAudioNode为类型为输入类型节点；\n
 *         3. 参数sourceAudioNode和destAudioNode为同一个节点；\n
 *         4. 参数sourceAudioNode为音源分离类型，但是destAudioNode类型不为输出类型接节点；\n
 *         5. 参数sourceAudioNode和destAudioNode不为同一个管线中的节点；\n
 *         6. 管线状态为运行状态，但是destAudioNode不为mix类型节点；\n
 *         7. 管线状态为运行状态，destAudioNode为mix类型节点，但是sourceAudioNode节点未连接输入类型节点。\n
 *         AUDIOSUITE_ERROR_INVALID_STATE：管线为无效状态。例如，无法找到输出节点。\n
 *         AUDIOSUITE_ERROR_TIMEOUT：操作处理超时。\n
 *         AUDIOSUITE_ERROR_SYSTEM：系统发生其他异常。
 * @since 22
 */
OH_AudioSuite_Result OH_AudioSuiteEngine_ConnectNodes(
    OH_AudioNode* sourceAudioNode, OH_AudioNode* destAudioNode);

/**
 * @brief 断开连接两个节点。
 *
 * 此操作将改变管道拓扑并可能导致数据丢失，建议在引擎停止状态下执行。
 *
 * @param sourceAudioNode 音频编创节点句柄。通过{@link OH_AudioSuiteEngine_CreateNode}获取句柄。
 * @param destAudioNode 音频编创节点句柄。通过{@link OH_AudioSuiteEngine_CreateNode}获取句柄。
 * @return AUDIOSUITE_SUCCESS：函数执行成功。\n
 *         AUDIOSUITE_ERROR_INVALID_PARAM：参数sourceAudioNode或destAudioNode为空指针。\n
 *         AUDIOSUITE_ERROR_NODE_NOT_EXIST：节点不存在或者当前节点已经被销毁。\n
 *         AUDIOSUITE_ERROR_UNSUPPORTED_OPERATION：不支持操作。\n
 *         可能的原因如下：\n
 *         1. 参数sourceAudioNode类型为输出类型节点；\n
 *         2. 参数destAudioNode为类型为输入类型节点；\n
 *         3. 参数sourceAudioNode和destAudioNode为同一个节点；\n
 *         4. 参数sourceAudioNode和destAudioNode不为同一个管线中的节点；\n
 *         5. 管线状态为运行状态，但是destAudioNode不为mix类型节点；\n
 *         6. 管线状态为运行状态，destAudioNode为mix类型节点，但是mix节点当前只连接了sourceAudioNode一个输入。\n
 *         AUDIOSUITE_ERROR_INVALID_STATE：管线为无效状态。例如，无法找到输出节点。\n
 *         AUDIOSUITE_ERROR_TIMEOUT：操作处理超时。\n
 *         AUDIOSUITE_ERROR_SYSTEM：系统发生其他异常。
 * @since 22
 */
OH_AudioSuite_Result OH_AudioSuiteEngine_DisconnectNodes(OH_AudioNode* sourceAudioNode, OH_AudioNode* destAudioNode);

/**
 * @brief 设置当前均衡器节点的频段增益效果。
 *
 * @param audioNode 音频编创节点句柄。通过{@link OH_AudioSuiteEngine_CreateNode}获取句柄。
 * @param frequencyBandGains 均衡器节点的均衡参数。
 * @return AUDIOSUITE_SUCCESS：函数执行成功。\n
 *         AUDIOSUITE_ERROR_NODE_NOT_EXIST：节点不存在或者当前节点已经被销毁。\n
 *         AUDIOSUITE_ERROR_UNSUPPORTED_OPERATION：audioNode节点类型为非均衡器节点。\n
 *         AUDIOSUITE_ERROR_INVALID_PARAM：\n
 *         可能的原因如下：\n
 *         1. 参数audioNode为空指针；\n
 *         2. 参数frequencyBandGains每个成员的值范围不在[-10, 10]。\n
 *         AUDIOSUITE_ERROR_TIMEOUT：操作处理超时。\n
 *         AUDIOSUITE_ERROR_SYSTEM：系统发生其他异常。
 * @since 22
 */
OH_AudioSuite_Result OH_AudioSuiteEngine_SetEqualizerFrequencyBandGains(
    OH_AudioNode* audioNode, OH_EqualizerFrequencyBandGains frequencyBandGains);

/**
 * @brief 获取当前均衡器节点的频段增益效果。
 *
 * @param audioNode 音频编创节点句柄。通过{@link OH_AudioSuiteEngine_CreateNode}获取句柄。
 * @param frequencyBandGains 均衡器节点的均衡参数。
 * @return AUDIOSUITE_SUCCESS：函数执行成功。\n
 *         AUDIOSUITE_ERROR_NODE_NOT_EXIST：节点不存在或者当前节点已经被销毁。\n
 *         AUDIOSUITE_ERROR_UNSUPPORTED_OPERATION：audioNode节点类型为非均衡器节点。\n
 *         AUDIOSUITE_ERROR_INVALID_PARAM：参数无效。例如，audioNode或frequencyBandGains为空指针。\n
 *         AUDIOSUITE_ERROR_TIMEOUT：操作处理超时。\n
 *         AUDIOSUITE_ERROR_SYSTEM：系统发生其他异常。
 * @since 22
 */
OH_AudioSuite_Result OH_AudioSuiteEngine_GetEqualizerFrequencyBandGains(
    OH_AudioNode* audioNode, OH_EqualizerFrequencyBandGains* frequencyBandGains);

/**
 * @brief 设置声场效果节点的配置参数。
 *
 * @param audioNode 音频编创节点句柄。通过{@link OH_AudioSuiteEngine_CreateNode}获取句柄。
 * @param soundFieldType 声场效果节点的配置参数。
 * @return AUDIOSUITE_SUCCESS：函数执行成功。\n
 *         AUDIOSUITE_ERROR_NODE_NOT_EXIST：节点不存在或者当前节点已经被销毁。\n
 *         AUDIOSUITE_ERROR_UNSUPPORTED_OPERATION：audioNode节点类型为非声场节点。\n
 *         AUDIOSUITE_ERROR_INVALID_PARAM：参数无效。例如，audioNode为空指针。\n
 *         AUDIOSUITE_ERROR_TIMEOUT：操作处理超时。\n
 *         AUDIOSUITE_ERROR_SYSTEM：系统发生其他异常。
 * @since 22
 */
OH_AudioSuite_Result OH_AudioSuiteEngine_SetSoundFieldType(OH_AudioNode* audioNode, OH_SoundFieldType soundFieldType);

/**
 * @brief 获取声场效果节点的配置参数。
 *
 * @param audioNode 音频编创节点句柄。通过{@link OH_AudioSuiteEngine_CreateNode}获取句柄。
 * @param soundFieldType 声场效果节点的配置参数。
 * @return AUDIOSUITE_SUCCESS：函数执行成功。\n
 *         AUDIOSUITE_ERROR_NODE_NOT_EXIST：节点不存在或者当前节点已经被销毁。\n
 *         AUDIOSUITE_ERROR_UNSUPPORTED_OPERATION：audioNode节点类型为非soundFieldType节点。\n
 *         AUDIOSUITE_ERROR_INVALID_PARAM：参数无效。例如，audioNode或soundFieldType为空指针。\n
 *         AUDIOSUITE_ERROR_TIMEOUT：操作处理超时。\n
 *         AUDIOSUITE_ERROR_SYSTEM：系统发生其他异常。
 * @since 22
 */
OH_AudioSuite_Result OH_AudioSuiteEngine_GetSoundFieldType(
    OH_AudioNode* audioNode, OH_SoundFieldType* soundFieldType);

/**
 * @brief 设置环境效果节点的配置参数。
 *
 * @param audioNode 音频编创节点句柄。通过{@link OH_AudioSuiteEngine_CreateNode}获取句柄。
 * @param environmentType 环境效果节点的配置参数。
 * @return AUDIOSUITE_SUCCESS：函数执行成功。\n
 *         AUDIOSUITE_ERROR_NODE_NOT_EXIST：节点不存在或者当前节点已经被销毁。\n
 *         AUDIOSUITE_ERROR_UNSUPPORTED_OPERATION：audioNode节点类型为非环境节点。\n
 *         AUDIOSUITE_ERROR_INVALID_PARAM：参数无效。例如，audioNode为空指针。\n
 *         AUDIOSUITE_ERROR_TIMEOUT：操作处理超时。\n
 *         AUDIOSUITE_ERROR_SYSTEM：系统发生其他异常。
 * @since 22
 */
OH_AudioSuite_Result OH_AudioSuiteEngine_SetEnvironmentType(
    OH_AudioNode* audioNode, OH_EnvironmentType environmentType);

/**
 * @brief 获取环境效果节点的配置参数。
 *
 * @param audioNode 音频编创节点句柄。通过{@link OH_AudioSuiteEngine_CreateNode}获取句柄。
 * @param environmentType 环境效果节点的配置参数。
 * @return AUDIOSUITE_SUCCESS：函数执行成功。\n
 *         AUDIOSUITE_ERROR_NODE_NOT_EXIST：节点不存在或者当前节点已经被销毁。\n
 *         AUDIOSUITE_ERROR_UNSUPPORTED_OPERATION：audioNode节点类型为非环境效果节点。\n
 *         AUDIOSUITE_ERROR_INVALID_PARAM：参数无效。例如，audioNode或environmentType为空指针。\n
 *         AUDIOSUITE_ERROR_TIMEOUT：操作处理超时。\n
 *         AUDIOSUITE_ERROR_SYSTEM：系统发生其他异常。
 * @since 22
 */
OH_AudioSuite_Result OH_AudioSuiteEngine_GetEnvironmentType(
    OH_AudioNode* audioNode, OH_EnvironmentType* environmentType);

/**
 * @brief 设置声音美化效果节点的配置参数。
 *
 * @param audioNode 音频编创节点句柄。通过{@link OH_AudioSuiteEngine_CreateNode}获取句柄。
 * @param voiceBeautifierType 声音美化效果节点的配置参数。
 * @return AUDIOSUITE_SUCCESS：函数执行成功。\n
 *         AUDIOSUITE_ERROR_NODE_NOT_EXIST：节点不存在或者当前节点已经被销毁。\n
 *         AUDIOSUITE_ERROR_UNSUPPORTED_OPERATION：audioNode节点类型为非声音美化效果节点。\n
 *         AUDIOSUITE_ERROR_INVALID_PARAM：参数无效。例如，audioNode为空指针。\n
 *         AUDIOSUITE_ERROR_TIMEOUT：操作处理超时。\n
 *         AUDIOSUITE_ERROR_SYSTEM：系统发生其他异常。
 * @since 22
 */
OH_AudioSuite_Result OH_AudioSuiteEngine_SetVoiceBeautifierType(
    OH_AudioNode* audioNode, OH_VoiceBeautifierType voiceBeautifierType);

/**
 * @brief 获取声音美化效果节点的配置参数。
 *
 * @param audioNode 音频编创节点句柄。通过{@link OH_AudioSuiteEngine_CreateNode}获取句柄。
 * @param voiceBeautifierType 声音美化效果节点的配置参数。
 * @return AUDIOSUITE_SUCCESS：函数执行成功。\n
 *         AUDIOSUITE_ERROR_NODE_NOT_EXIST：节点不存在或者当前节点已经被销毁。\n
 *         AUDIOSUITE_ERROR_UNSUPPORTED_OPERATION：audioNode节点类型为非声音美化效果节点。\n
 *         AUDIOSUITE_ERROR_INVALID_PARAM：参数无效。
 *         例如，audioNode或voiceBeautifierType为空指针。\n
 *         AUDIOSUITE_ERROR_TIMEOUT：操作处理超时。\n
 *         AUDIOSUITE_ERROR_SYSTEM：系统发生其他异常。
 * @since 22
 */
OH_AudioSuite_Result OH_AudioSuiteEngine_GetVoiceBeautifierType(
    OH_AudioNode* audioNode, OH_VoiceBeautifierType* voiceBeautifierType);

/**
 * @brief 查询当前系统是否支持创建指定的节点类型，避免节点创建失败。
 *
 * 调用该接口时不依赖引擎及管线状态，仅跟系统相关，无需创建引擎及管线。\n
 * 在创建前用来查询是否可以创造该类型节点，避免节点创建失败。
 *
 * @param nodeType 待查的节点类型。
 * @param isSupported 表示是否支持当前节点的创建。false表示未支持，true表示已支持。
 * @return AUDIOSUITE_SUCCESS：查询函数执行成功。\n
 *         AUDIOSUITE_ERROR_INVALID_PARAM：传入非法参数。
 *         例如，入参nodeType不在OH_AudioNode_Type枚举类型范围内、isSupported为空指针等。\n
 *         AUDIOSUITE_ERROR_SYSTEM：系统发生其他异常。
 * @since 22
 */
OH_AudioSuite_Result OH_AudioSuiteEngine_IsNodeTypeSupported(OH_AudioNode_Type nodeType, bool* isSupported);

#ifdef __cplusplus
}
#endif
/** @} */
#endif // NATIVE_AUDIO_SUITE_ENGINE_H